home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Language/OS - Multiplatform Resource Library
/
LANGUAGE OS.iso
/
a_utils
/
_archvrs
/
amiga
/
pplib.lzh
/
PPLib
/
doc
/
pplib.doc
Wrap
Text File
|
1991-11-10
|
21KB
|
621 lines
TABLE OF CONTENTS
powerpacker.library/ppAllocCrunchInfo
powerpacker.library/ppCalcChecksum
powerpacker.library/ppCalcPasskey
powerpacker.library/ppCrunchBuffer
powerpacker.library/ppDecrunchBuffer
powerpacker.library/ppDecrypt
powerpacker.library/ppEnterPassword
powerpacker.library/ppErrorMessage
powerpacker.library/ppFreeCrunchInfo
powerpacker.library/ppGetPassword
powerpacker.library/ppLoadData
powerpacker.library/ppWriteDataHeader
powerpacker.library/ppAllocCrunchInfo powerpacker.library/ppAllocCrunchInfo
NAME ppAllocCrunchInfo() (V35)
crunchinfo = ppAllocCrunchInfo (efficiency, speedup, function, userdata);
APTR ppAllocCrunchInfo (ULONG, ULONG, BOOL (*)(), APTR);
D0 D0 D1 A0 A1
DESCRIPTION
Allocate all the necessary memory needed to crunch a buffer. This
function must be called before using ppCrunchBuffer. You must pass
the crunching efficiency and the size of the speedup buffer.
You can pass a callback function to be called during crunching. Use this
type of function:
BOOL __stdargs myFunction (ULONG lensofar, ULONG crunlen,
ULONG totlen, APTR userdata);
If you do not wish to use this feature pass a NULL. The function can be
used for two things:
o to display the percentage crunched and gain so far.
o to allow the user to abort crunching.
Your function will be passed four arguments (on the stack, normal C
conventions):
lensofar - length of part crunched so far.
crunlen - crunched length of lensofar.
totlen - total length of buffer.
userdata - the userdata you provided to ppAllocCrunchInfo().
If your function returns a non-zero value the crunching will continue,
returning zero will abort crunching.
SAS/C users shouldn't forget __saveds if they compiled their program with
the small data model and wish to use global data in their function.
If you write your function in assembly please preserve all registers.
Example:
BOOL __stdargs __saveds myfunc (ULONG sofar, ULONG crunlen,
ULONG totlen, APTR userdata)
{
struct IntuiMessage *msg;
UWORD code;
if (sofar) {
sprintf (buff, "%ld%% crunched. (%ld%% gain) ",
(sofar * 100) / totlen, 100 - (100 * crunlen) / sofar);
PrtMsg (buff, BLACK|AT_START);
}
while (msg = (struct IntuiMessage *)GetMsg (win->UserPort)) {
code = msg->Code;
ReplyMsg ((struct Message *)msg);
if (code == 0x3 /* CTRL-C */) return (FALSE);
}
return (TRUE);
}
Finally note that you may scratch the A4 register. This is made possible
to help people who wish to use 'userdata' to pass A4 (C data pointer).
INPUTS
efficiency - the efficiency of the crunching. One of the
following (defined in "libraries/ppbase.[hi]"):
CRUN_FAST
CRUN_MEDIOCRE
CRUN_GOOD
CRUN_VERYGOOD
CRUN_BEST
speedup - size of speedup buffer to be used. One of the
following (defined in "libraries/ppbase.[hi]"):
SPEEDUP_BUFFSMALL - from 3K (fast) to 33K (best)
SPEEDUP_BUFFMEDIUM - from 5K (fast) to 65K (best)
SPEEDUP_BUFFLARGE - from 196K (fast) to 256K (best)
function - callback function to be called every so often during
crunching. Can be used to display percentage crunched
so far and to abort crunching.
userdata - anything you wish. Will be passed to your callback function.
RESULT
crunchinfo - pointer to private crunchinfo structure to be passed to
ppCrunchBuffer (use ppFreeCrunchInfo to deallocate).
NOTE
'crunchinfo' may be re-used to crunch several buffers.
BUGS
none known
SEE ALSO
ppFreeCrunchInfo(), ppCrunchBuffer()
powerpacker.library/ppCalcChecksum powerpacker.library/ppCalcChecksum
NAME ppCalcChecksum()
sum = ppCalcChecksum (string);
ULONG ppCalcChecksum (char *);
D0:16 A0
DESCRIPTION
This function calculates a 16 bit checksum of a given string of
characters.
INPUTS
string - pointer to a null terminated character string.
RESULT
sum - checksum of 'string'.
NOTE
Function used to check if a password is correct.
Upper 16 bits of checksum are 0.
BUGS
none
SEE ALSO
ppLoadData()
ppDecrunchBuffer()
ppDecrypt()
ppCalcPasskey()
powerpacker.library/ppCalcPasskey powerpacker.library/ppCalcPasskey
NAME ppCalcPasskey()
key = ppCalcPasskey (password);
ULONG ppCalcPasskey (char *);
D0 A0
DESCRIPTION
This function calculates the 32 bit key associated with the given
password to encrypt/decrypt crunched files with.
INPUTS
string - pointer to a null terminated character string.
RESULT
key - passkey corresponding to the given password.
NOTE
Function used to decrypt encrypted files.
BUGS
none
SEE ALSO
ppDecrunchBuffer()
ppDecrypt()
ppCalcChecksum()
powerpacker.library/ppCrunchBuffer powerpacker.library/ppCrunchBuffer
NAME ppCrunchBuffer() (V35)
crunchedlen = ppCrunchBuffer (crunchinfo, buffer, len);
ULONG ppCrunchBuffer (APTR, UBYTE *, ULONG);
D0 A0 A1 D0
DESCRIPTION
Crunch the buffer pointed to by 'buffer' and of length (in bytes) 'len'.
'crunchinfo' must have been previously allocated by ppAllocCrunchInfo().
During crunching your callback function will be called (if you have
provided one). See the autodoc for ppAllocCrunchInfo() for more
information.
The value returned is the length of the crunched buffer. If you wish to
save this crunched buffer as a PowerPacker data file you should first
write the data header using ppWriteDataHeader() en then write the
crunched buffer.
INPUTS
crunchinfo - pointer to private crunchinfo structure returned by
ppAllocCrunchInfo().
buffer - pointer to buffer to be crunched.
len - length of buffer to be crunched.
RESULT
crunchedlen - length of crunched buffer. In case of an error
'crunchedlen' may also equal PP_CRUNCHABORTED or
PP_BUFFEROVERFLOW. Be sure to check this!
NOTE
Be sure you know what you are doing when you intend to use this function.
You can easily crash your Amiga by passing wrong arguments or by writing
a faulty callback function.
BUGS
none known
SEE ALSO
ppAllocCrunchInfo(), ppFreeCrunchInfo()
powerpacker.library/ppDecrunchBuffer powerpacker.library/ppDecrunchBuffer
NAME ppDecrunchBuffer()
ppDecrunchBuffer (endcrun, decrbuff, effptr, col);
void ppDecrunchBuffer (UBYTE *, UBYTE *, ULONG *, ULONG);
A0 A1 A2 D0
DESCRIPTION
Function to decrunch from one memory location to another. The address of
the destination can be as close as 8 bytes after the start address of
the source, so you can decrunch a file with almost no memory overhead.
If you wish to call this function you need to know the format of a
crunched file:
1 longword identifier 'PP20' or 'PX20'
[1 word checksum (if 'PX20') $ssss]
1 longword efficiency $eeeeeeee
X longwords crunched file $cccccccc,$cccccccc,...
1 longword decrunch info 'decrlen' << 8 | '8 bits other info'
The following procedure must be followed to decrunch a file:
First you must read 'decrunch info' to find the length of the decrunched
file, then you must allocate memory to decrunch it in (shift 'decrunch
info' right 8 bits and add a safety margin (8 bytes) to get the length
of this memory block). If the file is encrypted ('PX20') you must call
ppDecrypt to decrypt the crunched part before calling ppDecrunchBuffer.
So:
- read identifier.
- if PX20, read checksum (16 bits, not 32!).
- read efficiency.
- read the longword of decrunch info at the end of the file.
- calculate 'decrlen'.
- allocate 'decrlen' + 8 (safety margin) bytes.
- load 'crunched file' and 'decrunch info' at start of allocated memory.
- if PX20, prompt for a password (check result of ppGetPassword()!).
- if PX20, calculate the passkey (use ppCalcPasskey).
- if PX20, call ppDecrypt to decrypt 'crunched file' only.
(NOT 'decrunch info'!)
- and finally call ppDecrunchBuffer() with 'endcrun' pointing right after
'decrunch info', 'decrbuff' pointing 8 bytes after where you loaded the
file and 'effptr' pointing to the 'efficieny' longword.
If this seems complicated that is probably because it is :-) ppLoadData
was written to make things simpler and should suffice in most cases.
INPUTS
endcrun - pointer just after the last byte of the crunched block.
decrbuff - pointer to beginning of memory to decrunch to (this must be
at least 8 bytes behind the start of the crunched file).
effptr - pointer to efficiency table.
col - decrunching effect (see ppLoadData).
RESULT
none
NOTE
This function is used by ppLoadData() and will probably not be used very
often on its own.
BUGS
none known
SEE ALSO
ppLoadData()
ppDecrypt()
ppCalcPasskey()
ppCalcChecksum()
ppGetPassword()
powerpacker.library/ppDecrypt powerpacker.library/ppDecrypt
NAME ppDecrypt()
ppDecrypt (buffer, len, key)
void ppDecrypt (UBYTE *, ULONG, ULONG);
A0 D0 D1
DESCRIPTION
This function will decrypt a memory region with a given passkey. It
must be called before calling ppDecrunchBuffer() (if the file was
encrypted).
INPUTS
buffer - start address of memory region to decrypt (word alligned !).
len - length in bytes of memory region to decrypt (rounded up to the
next multiple of 4).
key - key of password as returned by ppCalcPasskey().
RESULT
none
NOTE
If you call this function before calling ppDecrunchBuffer make sure you
decrypt the correct memory region, don't decrypt the last longword !
BUGS
none
SEE ALSO
ppDecrunchBuffer()
ppCalcChecksum()
ppCalcPasskey()
ppLoadData()
powerpacker.library/ppEnterPassword powerpacker.library/ppEnterPassword
NAME ppEnterPassword() (V35)
bool = ppEnterPassword (screen, buffer);
BOOL ppEnterPassword (struct Screen *, char *);
D0 A0 A1
DESCRIPTION
reqtools.library _MUST_ be available!
Opens a small requester to prompt the user for a password. The password
will not be visible when typed. Returns when the user has succesfully
entered a password AND a verification.
When buffer already holds a string on entry, a 'Last' gadget will appear
in the requester so the user may re-enter his last password without
retyping it. It is up to you to support this feature. If you do not wish
to support this make sure buffer holds an empty string (buffer[0] = 0).
INPUTS
screen - screen where the requester should appear or NULL.
buffer - buffer to hold the password. Must be at least 17 bytes big!
RESULT
bool - TRUE if a password was entered (can be found in buffer), FALSE
if user aborted the requester.
NOTE
The contents of the buffer will NOT change if the requester is aborted.
Automatically adjusts the requester to the screen's font.
ppEnterPassword() checks the pr_WindowPtr of your process to find the
screen to put the requester on (if screen == NULL).
BUGS
none known
SEE ALSO
powerpacker.library/ppErrorMessage powerpacker.library/ppErrorMessage
NAME ppErrorMessage() (V35)
message = ppErrorMessage (errorcode);
char *ppErrorMessage (ULONG);
D0 D0
DESCRIPTION
Returns a pointer to a null-terminated string holding a descriptive
error message for the supplied error code.
Currently only works for error codes returned by ppLoadData().
INPUTS
errorcode - error code returned by ppLoadData().
RESULT
message - pointer to error message (null terminated string) associated
with error code.
BUGS
none known
SEE ALSO
ppLoadData()
powerpacker.library/ppFreeCrunchInfo powerpacker.library/ppFreeCrunchInfo
NAME ppFreeCrunchInfo() (V35)
ppFreeCrunchInfo (crunchinfo);
void ppFreeCrunchInfo (APTR);
A0
DESCRIPTION
Free all memory associated with the private crunchinfo structure
returned by ppAllocCrunchInfo().
INPUTS
crunchinfo - pointer to private crunchinfo structure.
RESULT
none
NOTE
crunchinfo may be NULL, no action will be taken.
BUGS
none known
SEE ALSO
ppAllocCrunchInfo(), ppCrunchBuffer()
powerpacker.library/ppGetPassword powerpacker.library/ppGetPassword
NAME ppGetPassword()
bool = ppGetPassword (screen, buffer, maxlen, checksum);
BOOL ppGetPassword (struct Screen *, UBYTE *, ULONG, ULONG);
D0 A0 A1 D0 D1:16
DESCRIPTION
reqtools.library _MUST_ be available!
Opens a small requester to prompt the user for a password. Returns when
the user enters a password with a checksum equal to 'checksum' or when
he has failed to enter a correct password (three chances). The password
will not be visible when typed.
INPUTS
screen - screen where the requester should appear.
buffer - buffer to hold correct password. Must at least 17 bytes big!
maxlen - maximum length of password, should always be 16.
checksum - checksum of password we are looking for.
RESULT
bool - TRUE when the correct password was entered (can be found in
buffer), FALSE when no correct password was given after three
attempts.
NOTE
New for V35: The contents of the buffer will NOT change if the requester
is aborted.
This function will be used by ppLoadData() to prompt for a password when
you called it with 'func' equal to NULL.
Automatically adjusts the requester to the screen's font.
ppGetPassword() checks the pr_WindowPtr of your process to find the
screen to put the requester on (if screen == NULL).
BUGS
none known
SEE ALSO
ppLoadData()
ppDecrunchBuffer()
powerpacker.library/ppLoadData powerpacker.library/ppLoadData
NAME ppLoadData()
error = ppLoadData (filename, col, memtype, &buffer, &len, func);
ULONG ppLoadData (char *, ULONG, ULONG, UBYTE **, ULONG *, BOOL (*)());
D0 A0 D0 D1 A1 A2 A3
DESCRIPTION
This function loads a file in memory. The memory necessary to load the
file will be allocated by this function. Files crunched with PowerPacker
will be decrunched, plain files will simply be loaded. If the file can't
be opened ".pp" will be appended before trying again. The address of the
loaded file will be stored in 'buffer', the length in 'len'. You must
free this memory yourself (see NOTE) !
The 'func' argument is the address of a function to be called when
ppLoadData() needs a password to decrypt an encrypted file. If you do
not want to load encrypted files call with func equal to -1, if you want
ppLoadData() to use ppGetPassword(), call with func equal to NULL.
If you wish to use your own password prompting function you must call
ppLoadData() with func equal to the address of this type of function:
BOOL __stdargs myFunction (UBYTE *password, ULONG checksum);
On entry 'password' points to a buffer to hold up to 16 characters and a
terminating zero (so 17 bytes in all), 'checksum' is the checksum of the
password we are looking for. Your function must prompt for a string and
compare the checksum with 'checksum' (use ppCalcChecksum() for this). If
they are equal you must store the string in 'password' (in C you can use
'strcpy') and return TRUE, if not you should give the user a few more
chances (usually three in all) and return FALSE if no correct password
was entered.
The two arguments are pushed on the stack according to C convention, so
if you write your function in assembly you will find the arguments on the
stack, the pointer to the buffer at 4(a7) and the checksum at 8(a7)
(longwords!). Assembly functions must preserve all registers !
SAS/C users shouldn't forget __saveds if they compiled their program with
the small data model and wish to use global data in their function.
INPUTS
filename - pointer to a null terminated pathname of the file to load.
col - the effect to be used during decrunching. One of the
following (defined in "libraries/ppbase.[hi]"):
DECR_COL0 - flash color 0
DECR_COL1 - flash color 1
DECR_POINTER - flash mouse pointer
DECR_SCROLL - weird stuff :-)
DECR_NONE - no decrunching effect
memtype - type of memory to allocate (see AllocMem()).
&buffer - address of (!) variable to hold memory location of loaded
file.
&len - address of (!) variable to hold length of loaded file.
func - function to be called to prompt the user for a password,
NULL for the the default password prompt and -1 for no
password prompt.
RESULT
error - 0 if all went ok, if not one of the following error codes will
be returned (defined in "libraries/ppbase.(h|i)"):
PP_OPENERR - unable to open file.
PP_READERR - read error.
PP_NOMEMORY - not enough memory to load file.
PP_CRYPTED - file is encrypted (only when 'func' == -1).
PP_PASSERR - incorrect password, 'func()' returned FALSE.
PP_EMPTYFILE - file is empty, there is nothing to load.
PP_UNKNOWNPP - crunched by unknown version of PowerPacker.
NOTE
Do not forget to free the memory allocated by this function !
Use "FreeMem (buffer, len);" before quitting your program, but only if
ppLoadData() didn't return an error.
After calling 'func()' ppLoadData() doesn't check the checksum again,
only the returned boolean. Therefore it is VERY important that your
function is correct and only returns TRUE when the entered password has
the correct checksum !
Don't forget to copy your string to the memory pointed to by 'password'
before leaving 'func()' ! This password is needed to decrypt the file !!
Note that 'password' is a C string and must be null terminated !
In case you call ppLoadData() with 'func' equal to NULL (use automatic
password prompting) the pr_WindowPtr of your Process will be used to
find the screen to open the password requester on. If pr_WindowPtr
equals 0 or -1 the WorkBench screen will be used, otherwise the screen
of the pr_WindowPtr window will be used. Only a process can call
ppLoadData() (it uses DOS) so pr_WindowPtr exists. Set it like this:
struct Window *yourwindow;
struct Process *proc;
APTR oldwinptr;
/* Open your screen and window... */
...
/* set pr_WindowPtr */
proc = (struct Process *)FindTask (NULL);
oldwinptr = proc->pr_WindowPtr;
proc->pr_WindowPtr = (APTR)yourwindow;
...
/* restore before quitting (VERY IMPORTANT !!) */
proc->pr_WindowPtr = oldwinptr;
exit (0);
BUGS
none known
SEE ALSO
exec.library/AllocMem(), exec.library/FreeMem(), ppCalcChecksum(),
ppErrorMessage(), ppGetPassword()
powerpacker.library/ppWriteDataHeader powerpacker.library/ppWriteDataHeader
NAME ppWriteDataHeader() (V35)
success = ppWriteDataHeader (lock, efficiency, crypt, checksum);
ULONG ppWriteDataHeader (BPTR, ULONG, BOOL, ULONG);
D0 D0 D1 D2 D3:16
DESCRIPTION
Use this function to write the PowerPacker data header at the
beginning of a file.
INPUTS
lock - BCPL pointer to a DOS file handle.
efficiency - efficiency used to crunch the buffer.
See ppAllocCrunchInfo(). (CRUN_FAST, ... ,CRUN_BEST)
crypt - TRUE for a header of an encrypted file, FALSE otherwise.
checksum - (if crypt = TRUE) checksum of password used to encrypt.
RESULT
success - TRUE on success, FALSE if a write error occured.
NOTE
BUGS
none known
SEE ALSO
ppAllocCrunchInfo(), ppDecrypt()